---
title: Get Started
hide_title: true
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Get Started with GitOps Run

GitOps Run supports two different modes of operation - directly on a
cluster or as sandboxed sessions. The sandboxed sessions are intended
for shared environments where multiple users are running their own
sessions, whereas the direct mode is intended for a local cluster.

## Direct mode

### Prerequisites
#### Required
- Install the GitOps CLI. See [the installation](../installation/weave-gitops.mdx#install-the-gitops-cli)

#### Optional
- This guide uses [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) for demonstrations, but it is not required to use GitOps Run
- The [Flux CLI](https://fluxcd.io/flux/installation/) is the quickest way to generate resource definitions, but the files can also be created manually

### Kubernetes cluster
To get started with GitOps Run, you need a Kubernetes cluster. There
are many tools to set up a local cluster for test and development
purposes.

**Note:** this tutorial assumes you have full control of your cluster - we
recommend a local cluster, but you can also use a remote cluster where
you have full `cluster-admin` privileges.

<Tabs>
<TabItem value="kind">

Install [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) and run

```bash
kind create cluster
```
</TabItem>
<TabItem value="k3d">

Install [k3d](https://k3d.io/) and run

```bash
k3d cluster create mycluster
```
</TabItem>
<TabItem value="minikube">

Install [minikube](https://minikube.sigs.k8s.io/docs/start/) and run

```bash
minikube start
```
</TabItem>
<TabItem value="docker desktop">

Install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and enable Kubernetes. Then run

```
kubectl config set-context docker-desktop
```
</TabItem>
<TabItem value="other">

GitOps Run works on any Kubernetes platform, but to avoid accidents
you have to explicitly white-list the context name.

First, find the name of the context where you want to run `gitops beta run` - in this example, there's a cluster with the name "dev":

```bash
$ kubectl config get-contexts
CURRENT   NAME                      CLUSTER                   AUTHINFO                  NAMESPACE
*         dev                       dev                       dev
```

Then, for any `gitops beta run` command in this guide, you'll have to add the flag `--allow-k8s-context=dev`
</TabItem>
</Tabs>

Before you continue, make sure `kubectl get nodes` returns a node which is `Ready`.

### Git repository

You need to set up a Git repository to put your GitOps manifests
in. Any Git repository would do, for example create a new
[github](https://github.com/new) repository and clone that. We use `podinfo-gitops-run`
as the repository name in this guide.

### Set up GitOps Run

To start GitOps Run, point it at the directory you want to keep your
application manifests. In this example, we will install a small demo application
[podinfo](https://github.com/stefanprodan/podinfo).

We will start it with `--no-session` as it's a single user
cluster which we want to use in direct mode. The port-forward points
at the podinfo pod we will create later.

```bash
export GITHUB_USER=<your github username>

# you can ignore these two commands if you already created and cloned your repository
git clone git@github.com:$GITHUB_USER/podinfo-gitops-run.git

cd podinfo-gitops-run
gitops beta run ./podinfo --no-session --port-forward namespace=dev,resource=svc/dev-podinfo,port=9898:9898
```

You will now be asked if you want to install Flux and the GitOps
[dashboard](../getting-started/intro.mdx). Answer yes and set a password, and
shortly after you should be able to [open the dashboard](http://localhost:9001)
to see what's in your cluster - including the resources that GitOps
Run is operating.

### Start modifying

GitOps Run will have created a directory `podinfo` in your
current directory. Inside that directory, there will only be a single
file `kustomization.yaml`.

To create the podinfo automation, we have to create the resources to
run podinfo - we'll create a new `Namespace`, a `HelmRepository` that
references the Helm repository where the manifests are stored, and a
`HelmRelease` that references the chart and version. We can use the
`flux` CLI to generate the resource definition, or we can just create
the yaml files ourselves.

<Tabs>
<TabItem value="flux">

```bash
cat <<EOF > ./podinfo/namespace.yaml
---
apiVersion: v1
kind: Namespace
metadata:
  name: dev
EOF
flux create source helm podinfo --url=https://stefanprodan.github.io/podinfo --namespace=dev --export > ./podinfo/podinfo-source.yaml
flux create helmrelease podinfo --source=HelmRepository/podinfo --chart=podinfo --export --namespace=dev --target-namespace=dev > ./podinfo/podinfo-helmrelease.yaml
```
</TabItem>
<TabItem value="yaml">

```yaml title="./podinfo/namespace.yaml"
---
apiVersion: v1
kind: Namespace
metadata:
  name: dev
```
```yaml title="./podinfo/podinfo-source.yaml"
---
apiVersion: source.toolkit.fluxcd.io/v1beta2
kind: HelmRepository
metadata:
  name: podinfo
  namespace: dev
spec:
  interval: 1m0s
  url: https://stefanprodan.github.io/podinfo
```

```yaml title="./podinfo/podinfo-helmrelease.yaml"
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: podinfo
  namespace: dev
spec:
  chart:
    spec:
      chart: podinfo
      reconcileStrategy: ChartVersion
      sourceRef:
        kind: HelmRepository
        name: podinfo
  interval: 1m0s
  targetNamespace: dev
```
</TabItem>
</Tabs>

The only remaining step is to import these files in the auto-generated
`kustomization.yaml`. Open it up, and you should see the following:

```yaml title="./podinfo/kustomization.yaml"
---
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources: [] # 👋 Start adding the resources you want to sync here
```

Change the last line so it instead looks like the following:

```yaml title="./podinfo/kustomization.yaml"
---
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
// highlight-start
resources:
  - namespace.yaml
  - podinfo-source.yaml
  - podinfo-helmrelease.yaml
// highlight-end
```

GitOps Run should now automatically upload these manifests and install
them. The dashboard should show you how the resources are being
reconciled, and when they're Ready you will be able to see podinfo
[here](http://localhost:9898).


### Update your app

Now that GitOps Run is continuously watching and reconciling your
local files onto your cluster, we can start modifying the resources.

We're going to be modifying the podinfo we set up in the previous
step. Open the current [podinfo](http://localhost:9898) and pay
attention to the background color.

Now, open your HelmRelease file and add the values at the bottom, as
indicated:

```yaml title="./podinfo/podinfo-helmrelease.yaml"
---
apiVersion: helm.toolkit.fluxcd.io/v2beta1
kind: HelmRelease
metadata:
  name: podinfo
  namespace: dev
spec:
  chart:
    spec:
      chart: podinfo
      reconcileStrategy: ChartVersion
      sourceRef:
        kind: HelmRepository
        name: podinfo
  interval: 1m0s
  targetNamespace: dev
// highlight-start
  values:
    ui:
      color: "#C32148"
// highlight-end
```

When you hit save, you'll see GitOps Run upload new files, and once
it's reconciled the podinfo has changed to a bright red.

### Turn on GitOps Mode

Now that we've used this interactive environment to set up the
resources we want, we can switch over to full GitOps mode, where Flux
is permanently pulling from your own Git repository.

The first run, when you turn off GitOps Run, it will ask you if you
want to bootstrap your cluster into GitOps mode. If you answer yes, it
will take you through a wizard to help you set up how you want it to
run - what repository, which branch, etc.

When you hit submit, it will set up the repository and branch, add
Flux manifests, as well as the files you were just working on. From
this point on, you can make persistent changes by pushing them to this
repository.
